ph-db

Java library with some common DB API, a special JDBC version and a JPA version based on EclipseLink.

Licensed under the Apache 2.0 license.

Maven usage

Add the following to your pom.xml to use this artifact, where x.y.z is to be replaced with the last released version:

<dependency>
  <groupId>com.helger.db</groupId>
  <artifactId>ph-db-api</artifactId>
  <version>x.y.z</version>
</dependency>

<dependency>
  <groupId>com.helger.db</groupId>
  <artifactId>ph-db-jdbc</artifactId>
  <version>x.y.z</version>
</dependency>

<dependency>
  <groupId>com.helger.db</groupId>
  <artifactId>ph-db-jpa</artifactId>
  <version>x.y.z</version>
</dependency>

<dependency>
  <groupId>com.helger.db</groupId>
  <artifactId>ph-db-flyway</artifactId>
  <version>x.y.z</version>
</dependency>

Note: prior to v8.0.0 the group ID was com.helger

News and noteworthy

v8.4.0 - 2026-05-01

• Updated to Flyway 12.5.0
• IExecutionTimeExceededCallback.onExecutionTimeExceeded now takes Duration parameters (aExecutionDuration, aLimitDuration) instead of long milliseconds — breaking signature change. LoggingExecutionTimeExceededCallback was updated accordingly.
• DBExecutor now stores the execution duration warning threshold as java.time.Duration internally. Added new primary setter setExecutionWarnDuration(Duration) and getter getExecutionWarnDuration(); the previously named setExecutionDurationWarn(Duration) / getExecutionDuration() / isExecutionDurationWarnEnabled() and the millis-based setExecutionDurationWarnMS(long) / getExecutionDurationWarnMS() are retained as @Deprecated(forRemoval = true) and delegate to the new methods. The new isExecutionWarnDurationEnabled() requires a strictly positive duration (> 0).
• DBExecutor.onExecutionTimeExceeded(String, long) was changed to onExecutionTimeExceeded(String, Duration) to match the new callback signature.
• JPAEnabledManager.onExecutionTimeExceeded(String, long) was changed to onExecutionTimeExceeded(String, Duration). Added new getDefaultExecutionWarnDuration() and setDefaultExecutionDuration(Duration) plus a DEFAULT_EXECUTION_WARN_DURATION constant; the existing getDefaultExecutionWarnTime(), setDefaultExecutionWarnTime(int) and DEFAULT_EXECUTION_WARN_TIME_MS are now @Deprecated(forRemoval = true).

v8.3.0 - 2026-05-01

• Removed OSGI bundling
• JdbcConfigurationConfig now accepts the duration grammar from ph-commons 12.2.5 (ConfigDurationParser) on five new configuration keys: execution-time-warning, pooling.max-wait, pooling.between-evictions-runs, pooling.min-evictable-idle, pooling.remove-abandoned-timeout. Values like 5s, 2m, 1h 30m are parsed to java.time.Duration. The legacy *.millis/*.ms keys remain supported for backward compatibility; the duration key wins when both are set, and a parse failure on the duration key falls back to the legacy key.
• Added five java.time.Duration-typed accessors on IJdbcDataSourceConfiguration / IJdbcConfiguration: getJdbcPoolingMaxWait(), getJdbcPoolingBetweenEvictionRuns(), getJdbcPoolingMinEvictableIdle(), getJdbcPoolingRemoveAbandonedTimeout(), getJdbcExecutionTimeWarning(). The Duration getters are now the primary API; the existing getJdbc*Millis() long-millis getters are retained as @Deprecated thin wrappers.
• JdbcConfiguration (POJO) now stores its five duration values as Duration internally. A new primary constructor accepts Duration parameters; the existing long-millis constructor is @Deprecated and delegates to it. Added matching DEFAULT_* Duration constants alongside the existing DEFAULT_*_MILLIS longs.
• DataSourceProviderFromJdbcConfiguration now consumes the new Duration accessors directly, removing the Duration.ofMillis(...) wrappers around millis getters.
• The legacy *.millis/*.ms configuration keys, the corresponding SUFFIX_*_MILLIS/SUFFIX_*_MS constants, the getConfigKey*Millis*() accessors, and the getJdbc*Millis() getters on IJdbcDataSourceConfiguration / IJdbcConfiguration / JdbcConfiguration / JdbcConfigurationConfig are now @Deprecated. A WARN-level log message is emitted at runtime when a legacy *.millis/*.ms configuration key is read, pointing at the new duration-grammar key.

v8.2.1 - 2026-04-12

• Extended IJdbcDataSourceConfiguration, JdbcConfiguration and JdbcConfigurationConfig with the testOnBorrow pooling parameter

v8.2.0 - 2026-04-12

• Added new submodule ph-db-flyway with FlywayMigrationRunner utility class for shared Flyway database migration setup
• Moved Flyway configuration classes (FlywayConfiguration, FlywayConfigurationBuilderConfig, IFlywayConfiguration) from ph-db-api (com.helger.db.api.flyway) to ph-db-flyway (com.helger.db.flyway) — breaking package change
• Extended IFlywayConfiguration with debugMode and repairMode flags

v8.1.3 - 2026-04-07

• Extended IJdbcConfiguration, JdbcConfiguration and JdbcConfigurationConfig with connection pooling parameters: max connections, max wait, between eviction runs, min evictable idle, and remove abandoned timeout
• DataSourceProviderFromJdbcConfiguration now directly handles the pooling parameter in a standard way
• Added optional flywayHistoryTable parameter to IFlywayConfiguration for customizing the Flyway history table name

v8.1.2 - 2026-02-22

• Updated to Apache Commons Pool 2.13.1
• Updated to Apache Commons DBCP 2.14.0
• Updated to EclipseLink 4.0.9
• DBResultField constructor now takes an empty String as well
• Renamed EDatabaseSystemType.MSSQL to SQLSERVER

v8.1.1 - 2025-12-10

• Added specific support for Oracle Timestamp handling

v8.1.0 - 2025-11-16

• Updated to ph-commons 12.1.0
• Using JSpecify annotations

v8.0.1 - 2025-09-19

• Added new class DBSystemHelper

v8.0.0 - 2025-08-25

• Requires Java 17 as the minimum version
• Updated to ph-commons 12.0.0
• Updated to MySQLConnector/J 9.4.0
• Changed the Maven group ID from com.helger to com.helger.db

v7.1.0 - 2025-04-11

• Updated to Apache Commons Pool 2.12.1
• Added new enum EDatabaseSystemType
• Added new package com.helger.db.api.flyway
• Added new package com.helger.db.api.config

v7.0.6 - 2024-09-20

• Updated to Protobuf 4.28.2 to fix CVE-2024-7254

v7.0.5 - 2024-08-09

• Updated to MySQLConnector/J 9.0.0
• Updated to Protobuf 4.x

v7.0.4 - 2024-03-27

• Updated to ph-commons 11.1.5
• Updated to MySQLConnector/J 8.3.0
• Updated to Apache Commons DBCP 2.12.0
• Created Java 21 compatibility

v7.0.3 - 2023-12-10

• Updated all dependencies

v7.0.2 - 2023-07-31

• Updated to ph-commons 11.1

v7.0.1 - 2023-01-12

• Updated to MySQLConnector/J 8.0.31 with new Maven coordinates
• Updated to Protobuf 3.21.12

v7.0.0 - 2023-01-09

• Using Java 11 as the baseline
• Updated to ph-commons 11
• Updated to EclipseLink 4.0.0

v6.7.4 - 2022-02-21

• Updated to H2 2.0.210
• Fixed a NullPointerException in CLOB handling

v6.7.3 - 2021-11-24

• Updated to MySQLConnector/J 8.0.25
• Added new class DBValueHelper
• Added new class AbstractJDBCEnabledManager

v6.7.2 - 2021-09-19

• Updated to Apache Commons Pool 2.11.1
• Extended the DBExecutor API slightly

v6.7.1 - 2021-08-20

• Updated to ph-commons 10.1
• Updated to MySQLConnector/J 8.0.25
• Updated to Apache Commons DBCP 2.9.0
• Updated to Apache Commons Pool 2.10.0
• Extended DBResultRow with additional methods

v6.7.0 - 2021-04-06

• Added option to enabled/disable the connection state handling (and disabled it by default)

v6.6.0 - 2021-03-21

• Updated to ph-commons 10
• Updated to EclipseLink 2.7.8
• Updated to MySQLConnector/J 8.0.23
• Added new class ConnectionFromDataSource that has increased flexibility

v6.5.0 - 2020-11-27

• Added conversion from CLOB to String - thanks to GG
• Commented out the parameter check in favour of the default JDBC driver - thanks to GG for pointing that out
• Removed the usage of Optional in the DBExecutor to more easily differentiate between "Error" and "Not found"

v6.4.0 - 2020-11-02

• Updated to MySQLConnector/J 8.0.21
• Improved debug logging in DBExecutor
• Made DBExecutor consistently not thread-safe
• Made some DBExectur methods static

v6.3.1 - 2020-09-30

• Updated to Apache Commons Pool 2.9.0
• Updated to Apache Commons DBCP 2.8.0

v6.3.0 - 2020-08-24

• Renamed AbsractConnector to AbstractDBConnector
• Removed AbstractDBConnector.getDatabaseName
• Added class AbstractDBConnector
• Dropped some specific connector implementations

v6.2.1 - 2020-08-20

• Updated to EclipseLink 2.7.7
• Updated to Apache Commons Pool 2.8.1
• Updated DBResultRow API

v6.2.0 - 2020-04-23

• Updated to Apache Commons Pool 2.8.0
• Updated to MySQLConnector/J 8.0.19
• Updated to EclipseLink 2.7.6
• Extended JDBCHelper return types
• Added simple transaction support in DBExecutor
• Updated to ph-commons 9.4.1

v6.1.5 - 2019-10-25

• Updated to Apache Commons Pool 2.7.0
• Updated to Apache Commons DBCP 2.7.0
• Updated to MySQLConnector/J 8.0.18
• Updated to H2 1.4.200
• Updated to EclipseLink 2.7.5
• The EclipseLinkLogger logs all error levels below WARNING as Info

v6.1.4 - 2019-03-27

• Updated to H2 1.4.199
• Replacing "javax.persistence 2.2.1" with "jakarta.persistence 2.2.2"

v6.1.3 - 2019-03-12

• Updated to EclipseLink 2.7.4
• Updated to MySQLConnector/J 8.0.15
• Updated to Apache Commons Pool 2.6.1
• Updated to Apache Commons DBCP 2.6.0
• Updated to H2 1.4.198

v6.1.2 - 2018-11-22

• Updated to EclipseLink 2.7.3
• Updated to MySQLConnector/J 8.0.13
• Updated to ph-commons 9.2.0

v6.1.1 - 2018-07-24

• Fixed OSGI ServiceProvider configuration
• Updated to EclipseLink 2.7.2
• Updated to Apache Commons DBCP 2.5.0
• Updated to Apache Commons Pool 2.6.0
• Catching an throwing Exception only (instead of Throwable)

v6.1.0 - 2018-04-23

• Updated to Apache Commons DBCP 2.2.0
• Updated to EclipseLink 2.7.1
• JPAEnabledManager now has the possibility to disable the execution time warning

v6.0.0 - 2017-12-20

• Updated to ph-commons 9.0.0
• Updated to H2 1.4.196
• Updated to EclipseLink 2.7.0
• Updated to Apache Commons Pool2 2.5.0

v5.0.1 - 2016-08-21

• Updated to ph-commons 8.4.x

v5.0.0 - 2016-06-11

• Requires at least JDK8

---

My personal Coding Styleguide | It is appreciated if you star the GitHub project if you like it.